home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_xemacs.idb / usr / freeware / lib / xemacs-20.4 / info / lispref.info-21.z / lispref.info-21
Encoding:
GNU Info File  |  1998-05-21  |  47.8 KB  |  1,089 lines

  1. This is Info file ../../info/lispref.info, produced by Makeinfo version
  2. 1.68 from the input file lispref.texi.
  3.  
  4.    Edition History:
  5.  
  6.    GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
  7. Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
  8. Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
  9. XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
  10. GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
  11. Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
  12. Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
  13. Reference Manual (for 19.15 and 20.1, 20.2) v3.2, April, May 1997
  14.  
  15.    Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
  16. Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
  17. Copyright (C) 1995, 1996 Ben Wing.
  18.  
  19.    Permission is granted to make and distribute verbatim copies of this
  20. manual provided the copyright notice and this permission notice are
  21. preserved on all copies.
  22.  
  23.    Permission is granted to copy and distribute modified versions of
  24. this manual under the conditions for verbatim copying, provided that the
  25. entire resulting derived work is distributed under the terms of a
  26. permission notice identical to this one.
  27.  
  28.    Permission is granted to copy and distribute translations of this
  29. manual into another language, under the above conditions for modified
  30. versions, except that this permission notice may be stated in a
  31. translation approved by the Foundation.
  32.  
  33.    Permission is granted to copy and distribute modified versions of
  34. this manual under the conditions for verbatim copying, provided also
  35. that the section entitled "GNU General Public License" is included
  36. exactly as in the original, and provided that the entire resulting
  37. derived work is distributed under the terms of a permission notice
  38. identical to this one.
  39.  
  40.    Permission is granted to copy and distribute translations of this
  41. manual into another language, under the above conditions for modified
  42. versions, except that the section entitled "GNU General Public License"
  43. may be included in a translation approved by the Free Software
  44. Foundation instead of in the original English.
  45.  
  46. 
  47. File: lispref.info,  Node: Accessing Documentation,  Next: Keys in Documentation,  Prev: Documentation Basics,  Up: Documentation
  48.  
  49. Access to Documentation Strings
  50. ===============================
  51.  
  52.  - Function: documentation-property SYMBOL PROPERTY &optional VERBATIM
  53.      This function returns the documentation string that is recorded in
  54.      SYMBOL's property list under property PROPERTY.  It retrieves the
  55.      text from a file if necessary, and runs `substitute-command-keys'
  56.      to substitute actual key bindings.  (This substitution is not done
  57.      if VERBATIM is non-`nil'; the VERBATIM argument exists only as of
  58.      Emacs 19.)
  59.  
  60.           (documentation-property 'command-line-processed
  61.              'variable-documentation)
  62.                => "t once command line has been processed"
  63.  
  64.           (symbol-plist 'command-line-processed)
  65.                => (variable-documentation 188902)
  66.  
  67.  - Function: documentation FUNCTION &optional VERBATIM
  68.      This function returns the documentation string of FUNCTION.  It
  69.      reads the text from a file if necessary.  Then (unless VERBATIM is
  70.      non-`nil') it calls `substitute-command-keys', to return a value
  71.      containing the actual (current) key bindings.
  72.  
  73.      The function `documentation' signals a `void-function' error if
  74.      FUNCTION has no function definition.  However, it is ok if the
  75.      function definition has no documentation string.  In that case,
  76.      `documentation' returns `nil'.
  77.  
  78.    Here is an example of using the two functions, `documentation' and
  79. `documentation-property', to display the documentation strings for
  80. several symbols in a `*Help*' buffer.
  81.  
  82.      (defun describe-symbols (pattern)
  83.        "Describe the XEmacs Lisp symbols matching PATTERN.
  84.      All symbols that have PATTERN in their name are described
  85.      in the `*Help*' buffer."
  86.        (interactive "sDescribe symbols matching: ")
  87.        (let ((describe-func
  88.               (function
  89.                (lambda (s)
  90.  
  91.      ;; Print description of symbol.
  92.                  (if (fboundp s)             ; It is a function.
  93.                      (princ
  94.                       (format "%s\t%s\n%s\n\n" s
  95.                         (if (commandp s)
  96.                             (let ((keys (where-is-internal s)))
  97.                               (if keys
  98.                                   (concat
  99.                                    "Keys: "
  100.                                    (mapconcat 'key-description
  101.                                               keys " "))
  102.                                 "Keys: none"))
  103.                           "Function")
  104.  
  105.      (or (documentation s)
  106.                             "not documented"))))
  107.      
  108.                  (if (boundp s)              ; It is a variable.
  109.  
  110.      (princ
  111.                       (format "%s\t%s\n%s\n\n" s
  112.                         (if (user-variable-p s)
  113.                             "Option " "Variable")
  114.  
  115.      (or (documentation-property
  116.                               s 'variable-documentation)
  117.                             "not documented")))))))
  118.              sym-list)
  119.  
  120.      ;; Build a list of symbols that match pattern.
  121.          (mapatoms (function
  122.                     (lambda (sym)
  123.                       (if (string-match pattern (symbol-name sym))
  124.                           (setq sym-list (cons sym sym-list))))))
  125.  
  126.      ;; Display the data.
  127.          (with-output-to-temp-buffer "*Help*"
  128.            (mapcar describe-func (sort sym-list 'string<))
  129.            (print-help-return-message))))
  130.  
  131.    The `describe-symbols' function works like `apropos', but provides
  132. more information.
  133.  
  134.      (describe-symbols "goal")
  135.      
  136.      ---------- Buffer: *Help* ----------
  137.      goal-column     Option
  138.      *Semipermanent goal column for vertical motion, as set by C-x C-n, or nil.
  139.  
  140.      set-goal-column Command: C-x C-n
  141.      Set the current horizontal position as a goal for C-n and C-p.
  142.  
  143.      Those commands will move to this position in the line moved to
  144.      rather than trying to keep the same horizontal position.
  145.      With a non-nil argument, clears out the goal column
  146.      so that C-n and C-p resume vertical motion.
  147.      The goal column is stored in the variable `goal-column'.
  148.  
  149.      temporary-goal-column   Variable
  150.      Current goal column for vertical motion.
  151.      It is the column where point was
  152.      at the start of current run of vertical motion commands.
  153.      When the `track-eol' feature is doing its job, the value is 9999.
  154.      ---------- Buffer: *Help* ----------
  155.  
  156.  - Function: Snarf-documentation FILENAME
  157.      This function is used only during XEmacs initialization, just
  158.      before the runnable XEmacs is dumped.  It finds the file offsets
  159.      of the documentation strings stored in the file FILENAME, and
  160.      records them in the in-core function definitions and variable
  161.      property lists in place of the actual strings.  *Note Building
  162.      XEmacs::.
  163.  
  164.      XEmacs finds the file FILENAME in the `lib-src' directory.  When
  165.      the dumped XEmacs is later executed, the same file is found in the
  166.      directory `doc-directory'.  The usual value for FILENAME is `DOC',
  167.      but this can be changed by modifying the variable
  168.      `internal-doc-file-name'.
  169.  
  170.  - Variable: internal-doc-file-name
  171.      This variable holds the name of the file containing documentation
  172.      strings of built-in symbols, usually `DOC'.  The full pathname of
  173.      the internal doc file is `(concat doc-directory
  174.      internal-doc-file-name)'.
  175.  
  176.  - Variable: doc-directory
  177.      This variable holds the name of the directory which contains the
  178.      "internal doc file" that contains documentation strings for
  179.      built-in and preloaded functions and variables.
  180.  
  181.      In most cases, this is the same as `exec-directory'.  They may be
  182.      different when you run XEmacs from the directory where you built
  183.      it, without actually installing it.  See `exec-directory' in *Note
  184.      Help Functions::.
  185.  
  186.      In older Emacs versions, `exec-directory' was used for this.
  187.  
  188.  - Variable: data-directory
  189.      This variable holds the name of the directory in which XEmacs finds
  190.      certain system independent documentation and text files that come
  191.      with XEmacs.  In older Emacs versions, `exec-directory' was used
  192.      for this.
  193.  
  194. 
  195. File: lispref.info,  Node: Keys in Documentation,  Next: Describing Characters,  Prev: Accessing Documentation,  Up: Documentation
  196.  
  197. Substituting Key Bindings in Documentation
  198. ==========================================
  199.  
  200.    When documentation strings refer to key sequences, they should use
  201. the current, actual key bindings.  They can do so using certain special
  202. text sequences described below.  Accessing documentation strings in the
  203. usual way substitutes current key binding information for these special
  204. sequences.  This works by calling `substitute-command-keys'.  You can
  205. also call that function yourself.
  206.  
  207.    Here is a list of the special sequences and what they mean:
  208.  
  209. `\[COMMAND]'
  210.      stands for a key sequence that will invoke COMMAND, or `M-x
  211.      COMMAND' if COMMAND has no key bindings.
  212.  
  213. `\{MAPVAR}'
  214.      stands for a summary of the value of MAPVAR, which should be a
  215.      keymap.  The summary is made by `describe-bindings'.
  216.  
  217. `\<MAPVAR>'
  218.      stands for no text itself.  It is used for a side effect: it
  219.      specifies MAPVAR as the keymap for any following `\[COMMAND]'
  220.      sequences in this documentation string.
  221.  
  222. `\='
  223.      quotes the following character and is discarded; this `\=\=' puts
  224.      `\=' into the output, and `\=\[' puts `\[' into the output.
  225.  
  226.    *Please note:* Each `\' must be doubled when written in a string in
  227. XEmacs Lisp.
  228.  
  229.  - Function: substitute-command-keys STRING
  230.      This function scans STRING for the above special sequences and
  231.      replaces them by what they stand for, returning the result as a
  232.      string.  This permits display of documentation that refers
  233.      accurately to the user's own customized key bindings.
  234.  
  235.    Here are examples of the special sequences:
  236.  
  237.      (substitute-command-keys
  238.         "To abort recursive edit, type: \\[abort-recursive-edit]")
  239.      => "To abort recursive edit, type: C-]"
  240.  
  241.      (substitute-command-keys
  242.         "The keys that are defined for the minibuffer here are:
  243.        \\{minibuffer-local-must-match-map}")
  244.      => "The keys that are defined for the minibuffer here are:
  245.      
  246.      ?               minibuffer-completion-help
  247.      SPC             minibuffer-complete-word
  248.      TAB             minibuffer-complete
  249.      LFD             minibuffer-complete-and-exit
  250.      RET             minibuffer-complete-and-exit
  251.      C-g             abort-recursive-edit
  252.      "
  253.      (substitute-command-keys
  254.         "To abort a recursive edit from the minibuffer, type\
  255.      \\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
  256.      => "To abort a recursive edit from the minibuffer, type C-g."
  257.  
  258.      (substitute-command-keys
  259.        "Substrings of the form \\=\\{MAPVAR} are replaced by summaries
  260.      \(made by describe-bindings) of the value of MAPVAR, taken as a keymap.
  261.      Substrings of the form \\=\\<MAPVAR> specify to use the value of MAPVAR
  262.      as the keymap for future \\=\\[COMMAND] substrings.
  263.      \\=\\= quotes the following character and is discarded;
  264.      thus, \\=\\=\\=\\= puts \\=\\= into the output,
  265.      and \\=\\=\\=\\[ puts \\=\\[ into the output.")
  266.      => "Substrings of the form \{MAPVAR} are replaced by summaries
  267.      (made by describe-bindings) of the value of MAPVAR, taken as a keymap.
  268.      Substrings of the form \<MAPVAR> specify to use the value of MAPVAR
  269.      as the keymap for future \[COMMAND] substrings.
  270.      \= quotes the following character and is discarded;
  271.      thus, \=\= puts \= into the output,
  272.      and \=\[ puts \[ into the output."
  273.  
  274. 
  275. File: lispref.info,  Node: Describing Characters,  Next: Help Functions,  Prev: Keys in Documentation,  Up: Documentation
  276.  
  277. Describing Characters for Help Messages
  278. =======================================
  279.  
  280.    These functions convert events, key sequences or characters to
  281. textual descriptions.  These descriptions are useful for including
  282. arbitrary text characters or key sequences in messages, because they
  283. convert non-printing and whitespace characters to sequences of printing
  284. characters.  The description of a non-whitespace printing character is
  285. the character itself.
  286.  
  287.  - Function: key-description SEQUENCE
  288.      This function returns a string containing the XEmacs standard
  289.      notation for the input events in SEQUENCE.  The argument SEQUENCE
  290.      may be a string, vector or list.  *Note Events::, for more
  291.      information about valid events.  See also the examples for
  292.      `single-key-description', below.
  293.  
  294.  - Function: single-key-description KEY
  295.      This function returns a string describing KEY in the standard
  296.      XEmacs notation for keyboard input.  A normal printing character
  297.      appears as itself, but a control character turns into a string
  298.      starting with `C-', a meta character turns into a string starting
  299.      with `M-', and space, linefeed, etc. appear as `SPC', `LFD', etc.
  300.      A symbol appears as the name of the symbol.  An event that is a
  301.      list appears as the name of the symbol in the CAR of the list.
  302.  
  303.           (single-key-description ?\C-x)
  304.                => "C-x"
  305.  
  306.           (key-description "\C-x \M-y \n \t \r \f123")
  307.                => "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3"
  308.  
  309.           (single-key-description 'kp_next)
  310.                => "kp_next"
  311.  
  312.           (single-key-description '(shift button1))
  313.                => "Sh-button1"
  314.  
  315.  - Function: text-char-description CHARACTER
  316.      This function returns a string describing CHARACTER in the
  317.      standard XEmacs notation for characters that appear in text--like
  318.      `single-key-description', except that control characters are
  319.      represented with a leading caret (which is how control characters
  320.      in XEmacs buffers are usually displayed).
  321.  
  322.           (text-char-description ?\C-c)
  323.                => "^C"
  324.  
  325.           (text-char-description ?\M-m)
  326.                => "M-m"
  327.  
  328.           (text-char-description ?\C-\M-m)
  329.                => "M-^M"
  330.  
  331. 
  332. File: lispref.info,  Node: Help Functions,  Next: Obsoleteness,  Prev: Describing Characters,  Up: Documentation
  333.  
  334. Help Functions
  335. ==============
  336.  
  337.    XEmacs provides a variety of on-line help functions, all accessible
  338. to the user as subcommands of the prefix `C-h', or on some keyboards,
  339. `help'.  For more information about them, see *Note Help: (emacs)Help.
  340. Here we describe some program-level interfaces to the same information.
  341.  
  342.  - Command: apropos REGEXP &optional DO-ALL PREDICATE
  343.      This function finds all symbols whose names contain a match for the
  344.      regular expression REGEXP, and returns a list of them (*note
  345.      Regular Expressions::.).  It also displays the symbols in a buffer
  346.      named `*Help*', each with a one-line description.
  347.  
  348.      If DO-ALL is non-`nil', then `apropos' also shows key bindings for
  349.      the functions that are found.
  350.  
  351.      If PREDICATE is non-`nil', it should be a function to be called on
  352.      each symbol that has matched REGEXP.  Only symbols for which
  353.      PREDICATE returns a non-`nil' value are listed or displayed.
  354.  
  355.      In the first of the following examples, `apropos' finds all the
  356.      symbols with names containing `exec'.  In the second example, it
  357.      finds and returns only those symbols that are also commands.  (We
  358.      don't show the output that results in the `*Help*' buffer.)
  359.  
  360.           (apropos "exec")
  361.                => (Buffer-menu-execute command-execute exec-directory
  362.               exec-path execute-extended-command execute-kbd-macro
  363.               executing-kbd-macro executing-macro)
  364.  
  365.           (apropos "exec" nil 'commandp)
  366.                => (Buffer-menu-execute execute-extended-command)
  367.  
  368.      `apropos' is used by various user-level commands, such as `C-h a'
  369.      (`hyper-apropos'), a graphical front-end to `apropos'; and `C-h A'
  370.      (`command-apropos'), which does an apropos over only those
  371.      functions which are user commands.  `command-apropos' calls
  372.      `apropos', specifying a PREDICATE to restrict the output to
  373.      symbols that are commands.  The call to `apropos' looks like this:
  374.  
  375.           (apropos string t 'commandp)
  376.  
  377.  - Variable: help-map
  378.      The value of this variable is a local keymap for characters
  379.      following the Help key, `C-h'.
  380.  
  381.  - Prefix Command: help-command
  382.      This symbol is not a function; its function definition is actually
  383.      the keymap known as `help-map'.  It is defined in `help.el' as
  384.      follows:
  385.  
  386.           (define-key global-map "\C-h" 'help-command)
  387.           (fset 'help-command help-map)
  388.  
  389.  - Function: print-help-return-message &optional FUNCTION
  390.      This function builds a string that explains how to restore the
  391.      previous state of the windows after a help command.  After
  392.      building the message, it applies FUNCTION to it if FUNCTION is
  393.      non-`nil'.  Otherwise it calls `message' to display it in the echo
  394.      area.
  395.  
  396.      This function expects to be called inside a
  397.      `with-output-to-temp-buffer' special form, and expects
  398.      `standard-output' to have the value bound by that special form.
  399.      For an example of its use, see the long example in *Note Accessing
  400.      Documentation::.
  401.  
  402.  - Variable: help-char
  403.      The value of this variable is the help character--the character
  404.      that XEmacs recognizes as meaning Help.  By default, it is the
  405.      character `?\^H' (ASCII 8), which is `C-h'.  When XEmacs reads this
  406.      character, if `help-form' is non-`nil' Lisp expression, it
  407.      evaluates that expression, and displays the result in a window if
  408.      it is a string.
  409.  
  410.      `help-char' can be a character or a key description such as `help'
  411.      or `(meta h)'.
  412.  
  413.      Usually the value of `help-form''s value is `nil'.  Then the help
  414.      character has no special meaning at the level of command input, and
  415.      it becomes part of a key sequence in the normal way.  The standard
  416.      key binding of `C-h' is a prefix key for several general-purpose
  417.      help features.
  418.  
  419.      The help character is special after prefix keys, too.  If it has no
  420.      binding as a subcommand of the prefix key, it runs
  421.      `describe-prefix-bindings', which displays a list of all the
  422.      subcommands of the prefix key.
  423.  
  424.  - Variable: help-form
  425.      If this variable is non-`nil', its value is a form to evaluate
  426.      whenever the character `help-char' is read.  If evaluating the form
  427.      produces a string, that string is displayed.
  428.  
  429.      A command that calls `next-command-event' or `next-event' probably
  430.      should bind `help-form' to a non-`nil' expression while it does
  431.      input.  (The exception is when `C-h' is meaningful input.)
  432.      Evaluating this expression should result in a string that explains
  433.      what the input is for and how to enter it properly.
  434.  
  435.      Entry to the minibuffer binds this variable to the value of
  436.      `minibuffer-help-form' (*note Minibuffer Misc::.).
  437.  
  438.  - Variable: prefix-help-command
  439.      This variable holds a function to print help for a prefix
  440.      character.  The function is called when the user types a prefix
  441.      key followed by the help character, and the help character has no
  442.      binding after that prefix.  The variable's default value is
  443.      `describe-prefix-bindings'.
  444.  
  445.  - Function: describe-prefix-bindings
  446.      This function calls `describe-bindings' to display a list of all
  447.      the subcommands of the prefix key of the most recent key sequence.
  448.      The prefix described consists of all but the last event of that
  449.      key sequence.  (The last event is, presumably, the help character.)
  450.  
  451.    The following two functions are found in the library `helper'.  They
  452. are for modes that want to provide help without relinquishing control,
  453. such as the "electric" modes.  You must load that library with
  454. `(require 'helper)' in order to use them.  Their names begin with
  455. `Helper' to distinguish them from the ordinary help functions.
  456.  
  457.  - Command: Helper-describe-bindings
  458.      This command pops up a window displaying a help buffer containing a
  459.      listing of all of the key bindings from both the local and global
  460.      keymaps.  It works by calling `describe-bindings'.
  461.  
  462.  - Command: Helper-help
  463.      This command provides help for the current mode.  It prompts the
  464.      user in the minibuffer with the message `Help (Type ? for further
  465.      options)', and then provides assistance in finding out what the key
  466.      bindings are, and what the mode is intended for.  It returns `nil'.
  467.  
  468.      This can be customized by changing the map `Helper-help-map'.
  469.  
  470. 
  471. File: lispref.info,  Node: Obsoleteness,  Prev: Help Functions,  Up: Documentation
  472.  
  473. Obsoleteness
  474. ============
  475.  
  476.    As you add functionality to a package, you may at times want to
  477. replace an older function with a new one.  To preserve compatibility
  478. with existing code, the older function needs to still exist; but users
  479. of that function should be told to use the newer one instead.  XEmacs
  480. Lisp lets you mark a function or variable as "obsolete", and indicate
  481. what should be used instead.
  482.  
  483.  - Function: make-obsolete FUNCTION NEW
  484.      This function indicates that FUNCTION is an obsolete function, and
  485.      the function NEW should be used instead.  The byte compiler will
  486.      issue a warning to this effect when it encounters a usage of the
  487.      older function, and the help system will also note this in the
  488.      function's documentation.  NEW can also be a string (if there is
  489.      not a single function with the same functionality any more), and
  490.      should be a descriptive statement, such as "use FOO or BAR
  491.      instead" or "this function is unnecessary".
  492.  
  493.  - Function: make-obsolete-variable VARIABLE NEW
  494.      This is like `make-obsolete' but is for variables instead of
  495.      functions.
  496.  
  497.  - Function: define-obsolete-function-alias OLDFUN NEWFUN
  498.      This function combines `make-obsolete' and `define-function',
  499.      declaring OLDFUN to be an obsolete variant of NEWFUN and defining
  500.      OLDFUN as an alias for NEWFUN.
  501.  
  502.  - Function: define-obsolete-variable-alias OLDVAR NEWVAR
  503.      This is like `define-obsolete-function-alias' but for variables.
  504.  
  505.    Note that you should not normally put obsoleteness information
  506. explicitly in a function or variable's doc string.  The obsoleteness
  507. information that you specify using the above functions will be displayed
  508. whenever the doc string is displayed, and by adding it explicitly the
  509. result is redundancy.
  510.  
  511.    Also, if an obsolete function is substantially the same as a newer
  512. one but is not actually an alias, you should consider omitting the doc
  513. string entirely (use a null string `""' as the doc string).  That way,
  514. the user is told about the obsoleteness and is forced to look at the
  515. documentation of the new function, making it more likely that he will
  516. use the new function.
  517.  
  518.  - Function: function-obsoleteness-doc FUNCTION
  519.      If FUNCTION is obsolete, this function returns a string describing
  520.      this.  This is the message that is printed out during byte
  521.      compilation or in the function's documentation.  If FUNCTION is
  522.      not obsolete, `nil' is returned.
  523.  
  524.  - Function: variable-obsoleteness-doc VARIABLE
  525.      This is like `function-obsoleteness-doc' but for variables.
  526.  
  527.    The obsoleteness information is stored internally by putting a
  528. property `byte-obsolete-info' (for functions) or
  529. `byte-obsolete-variable' (for variables) on the symbol that specifies
  530. the obsolete function or variable.  For more information, see the
  531. implementation of `make-obsolete' and `make-obsolete-variable' in
  532. `lisp/bytecomp/bytecomp-runtime.el'.
  533.  
  534. 
  535. File: lispref.info,  Node: Files,  Next: Backups and Auto-Saving,  Prev: Documentation,  Up: Top
  536.  
  537. Files
  538. *****
  539.  
  540.    In XEmacs, you can find, create, view, save, and otherwise work with
  541. files and file directories.  This chapter describes most of the
  542. file-related functions of XEmacs Lisp, but a few others are described in
  543. *Note Buffers::, and those related to backups and auto-saving are
  544. described in *Note Backups and Auto-Saving::.
  545.  
  546.    Many of the file functions take one or more arguments that are file
  547. names.  A file name is actually a string.  Most of these functions
  548. expand file name arguments using `expand-file-name', so that `~' is
  549. handled correctly, as are relative file names (including `../').  These
  550. functions don't recognize environment variable substitutions such as
  551. `$HOME'.  *Note File Name Expansion::.
  552.  
  553. * Menu:
  554.  
  555. * Visiting Files::           Reading files into Emacs buffers for editing.
  556. * Saving Buffers::           Writing changed buffers back into files.
  557. * Reading from Files::       Reading files into buffers without visiting.
  558. * Writing to Files::         Writing new files from parts of buffers.
  559. * File Locks::               Locking and unlocking files, to prevent
  560.                                simultaneous editing by two people.
  561. * Information about Files::  Testing existence, accessibility, size of files.
  562. * Changing File Attributes:: Renaming files, changing protection, etc.
  563. * File Names::               Decomposing and expanding file names.
  564. * Contents of Directories::  Getting a list of the files in a directory.
  565. * Create/Delete Dirs::         Creating and Deleting Directories.
  566. * Magic File Names::         Defining "magic" special handling
  567.                    for certain file names.
  568. * Partial Files::            Treating a section of a buffer as a file.
  569. * Format Conversion::        Conversion to and from various file formats.
  570. * Files and MS-DOS::         Distinguishing text and binary files on MS-DOS.
  571.  
  572. 
  573. File: lispref.info,  Node: Visiting Files,  Next: Saving Buffers,  Up: Files
  574.  
  575. Visiting Files
  576. ==============
  577.  
  578.    Visiting a file means reading a file into a buffer.  Once this is
  579. done, we say that the buffer is "visiting" that file, and call the file
  580. "the visited file" of the buffer.
  581.  
  582.    A file and a buffer are two different things.  A file is information
  583. recorded permanently in the computer (unless you delete it).  A buffer,
  584. on the other hand, is information inside of XEmacs that will vanish at
  585. the end of the editing session (or when you kill the buffer).  Usually,
  586. a buffer contains information that you have copied from a file; then we
  587. say the buffer is visiting that file.  The copy in the buffer is what
  588. you modify with editing commands.  Such changes to the buffer do not
  589. change the file; therefore, to make the changes permanent, you must
  590. "save" the buffer, which means copying the altered buffer contents back
  591. into the file.
  592.  
  593.    In spite of the distinction between files and buffers, people often
  594. refer to a file when they mean a buffer and vice-versa.  Indeed, we say,
  595. "I am editing a file," rather than, "I am editing a buffer that I will
  596. soon save as a file of the same name."  Humans do not usually need to
  597. make the distinction explicit.  When dealing with a computer program,
  598. however, it is good to keep the distinction in mind.
  599.  
  600. * Menu:
  601.  
  602. * Visiting Functions::         The usual interface functions for visiting.
  603. * Subroutines of Visiting::    Lower-level subroutines that they use.
  604.  
  605. 
  606. File: lispref.info,  Node: Visiting Functions,  Next: Subroutines of Visiting,  Up: Visiting Files
  607.  
  608. Functions for Visiting Files
  609. ----------------------------
  610.  
  611.    This section describes the functions normally used to visit files.
  612. For historical reasons, these functions have names starting with
  613. `find-' rather than `visit-'.  *Note Buffer File Name::, for functions
  614. and variables that access the visited file name of a buffer or that
  615. find an existing buffer by its visited file name.
  616.  
  617.    In a Lisp program, if you want to look at the contents of a file but
  618. not alter it, the fastest way is to use `insert-file-contents' in a
  619. temporary buffer.  Visiting the file is not necessary and takes longer.
  620. *Note Reading from Files::.
  621.  
  622.  - Command: find-file FILENAME
  623.      This command selects a buffer visiting the file FILENAME, using an
  624.      existing buffer if there is one, and otherwise creating a new
  625.      buffer and reading the file into it.  It also returns that buffer.
  626.  
  627.      The body of the `find-file' function is very simple and looks like
  628.      this:
  629.  
  630.           (switch-to-buffer (find-file-noselect filename))
  631.  
  632.      (See `switch-to-buffer' in *Note Displaying Buffers::.)
  633.  
  634.      When `find-file' is called interactively, it prompts for FILENAME
  635.      in the minibuffer.
  636.  
  637.  - Function: find-file-noselect FILENAME &optional NOWARN
  638.      This function is the guts of all the file-visiting functions.  It
  639.      finds or creates a buffer visiting the file FILENAME, and returns
  640.      it.  It uses an existing buffer if there is one, and otherwise
  641.      creates a new buffer and reads the file into it.  You may make the
  642.      buffer current or display it in a window if you wish, but this
  643.      function does not do so.
  644.  
  645.      When `find-file-noselect' uses an existing buffer, it first
  646.      verifies that the file has not changed since it was last visited or
  647.      saved in that buffer.  If the file has changed, then this function
  648.      asks the user whether to reread the changed file.  If the user says
  649.      `yes', any changes previously made in the buffer are lost.
  650.  
  651.      If `find-file-noselect' needs to create a buffer, and there is no
  652.      file named FILENAME, it displays the message `New file' in the
  653.      echo area, and leaves the buffer empty.
  654.  
  655.      If NO-WARN is non-`nil', various warnings that XEmacs normally
  656.      gives (e.g. if another buffer is already visiting FILENAME but
  657.      FILENAME has been removed from disk since that buffer was created)
  658.      are suppressed.
  659.  
  660.      The `find-file-noselect' function calls `after-find-file' after
  661.      reading the file (*note Subroutines of Visiting::.).  That function
  662.      sets the buffer major mode, parses local variables, warns the user
  663.      if there exists an auto-save file more recent than the file just
  664.      visited, and finishes by running the functions in
  665.      `find-file-hooks'.
  666.  
  667.      The `find-file-noselect' function returns the buffer that is
  668.      visiting the file FILENAME.
  669.  
  670.           (find-file-noselect "/etc/fstab")
  671.                => #<buffer fstab>
  672.  
  673.  - Command: find-file-other-window FILENAME
  674.      This command selects a buffer visiting the file FILENAME, but does
  675.      so in a window other than the selected window.  It may use another
  676.      existing window or split a window; see *Note Displaying Buffers::.
  677.  
  678.      When this command is called interactively, it prompts for FILENAME.
  679.  
  680.  - Command: find-file-read-only FILENAME
  681.      This command selects a buffer visiting the file FILENAME, like
  682.      `find-file', but it marks the buffer as read-only.  *Note Read
  683.      Only Buffers::, for related functions and variables.
  684.  
  685.      When this command is called interactively, it prompts for FILENAME.
  686.  
  687.  - Command: view-file FILENAME
  688.      This command visits FILENAME in View mode, and displays it in a
  689.      recursive edit, returning to the previous buffer when done.  View
  690.      mode is a mode that allows you to skim rapidly through the file
  691.      but does not let you modify it.  Entering View mode runs the
  692.      normal hook `view-mode-hook'.  *Note Hooks::.
  693.  
  694.      When `view-file' is called interactively, it prompts for FILENAME.
  695.  
  696.  - Variable: find-file-hooks
  697.      The value of this variable is a list of functions to be called
  698.      after a file is visited.  The file's local-variables specification
  699.      (if any) will have been processed before the hooks are run.  The
  700.      buffer visiting the file is current when the hook functions are
  701.      run.
  702.  
  703.      This variable works just like a normal hook, but we think that
  704.      renaming it would not be advisable.
  705.  
  706.  - Variable: find-file-not-found-hooks
  707.      The value of this variable is a list of functions to be called when
  708.      `find-file' or `find-file-noselect' is passed a nonexistent file
  709.      name.  `find-file-noselect' calls these functions as soon as it
  710.      detects a nonexistent file.  It calls them in the order of the
  711.      list, until one of them returns non-`nil'.  `buffer-file-name' is
  712.      already set up.
  713.  
  714.      This is not a normal hook because the values of the functions are
  715.      used and they may not all be called.
  716.  
  717. 
  718. File: lispref.info,  Node: Subroutines of Visiting,  Prev: Visiting Functions,  Up: Visiting Files
  719.  
  720. Subroutines of Visiting
  721. -----------------------
  722.  
  723.    The `find-file-noselect' function uses the `create-file-buffer' and
  724. `after-find-file' functions as subroutines.  Sometimes it is useful to
  725. call them directly.
  726.  
  727.  - Function: create-file-buffer FILENAME
  728.      This function creates a suitably named buffer for visiting
  729.      FILENAME, and returns it.  It uses FILENAME (sans directory) as
  730.      the name if that name is free; otherwise, it appends a string such
  731.      as `<2>' to get an unused name.  See also *Note Creating Buffers::.
  732.  
  733.      *Please note:* `create-file-buffer' does *not* associate the new
  734.      buffer with a file and does not select the buffer.  It also does
  735.      not use the default major mode.
  736.  
  737.           (create-file-buffer "foo")
  738.                => #<buffer foo>
  739.           (create-file-buffer "foo")
  740.                => #<buffer foo<2>>
  741.           (create-file-buffer "foo")
  742.                => #<buffer foo<3>>
  743.  
  744.      This function is used by `find-file-noselect'.  It uses
  745.      `generate-new-buffer' (*note Creating Buffers::.).
  746.  
  747.  - Function: after-find-file &optional ERROR WARN NOAUTO
  748.      This function sets the buffer major mode, and parses local
  749.      variables (*note Auto Major Mode::.).  It is called by
  750.      `find-file-noselect' and by the default revert function (*note
  751.      Reverting::.).
  752.  
  753.      If reading the file got an error because the file does not exist,
  754.      but its directory does exist, the caller should pass a non-`nil'
  755.      value for ERROR.  In that case, `after-find-file' issues a warning:
  756.      `(New File)'.  For more serious errors, the caller should usually
  757.      not call `after-find-file'.
  758.  
  759.      If WARN is non-`nil', then this function issues a warning if an
  760.      auto-save file exists and is more recent than the visited file.
  761.  
  762.      If NOAUTO is non-`nil', then this function does not turn on
  763.      auto-save mode; otherwise, it does.
  764.  
  765.      The last thing `after-find-file' does is call all the functions in
  766.      `find-file-hooks'.
  767.  
  768. 
  769. File: lispref.info,  Node: Saving Buffers,  Next: Reading from Files,  Prev: Visiting Files,  Up: Files
  770.  
  771. Saving Buffers
  772. ==============
  773.  
  774.    When you edit a file in XEmacs, you are actually working on a buffer
  775. that is visiting that file--that is, the contents of the file are
  776. copied into the buffer and the copy is what you edit.  Changes to the
  777. buffer do not change the file until you "save" the buffer, which means
  778. copying the contents of the buffer into the file.
  779.  
  780.  - Command: save-buffer &optional BACKUP-OPTION
  781.      This function saves the contents of the current buffer in its
  782.      visited file if the buffer has been modified since it was last
  783.      visited or saved.  Otherwise it does nothing.
  784.  
  785.      `save-buffer' is responsible for making backup files.  Normally,
  786.      BACKUP-OPTION is `nil', and `save-buffer' makes a backup file only
  787.      if this is the first save since visiting the file.  Other values
  788.      for BACKUP-OPTION request the making of backup files in other
  789.      circumstances:
  790.  
  791.         * With an argument of 4 or 64, reflecting 1 or 3 `C-u''s, the
  792.           `save-buffer' function marks this version of the file to be
  793.           backed up when the buffer is next saved.
  794.  
  795.         * With an argument of 16 or 64, reflecting 2 or 3 `C-u''s, the
  796.           `save-buffer' function unconditionally backs up the previous
  797.           version of the file before saving it.
  798.  
  799.  - Command: save-some-buffers &optional SAVE-SILENTLY-P EXITING
  800.      This command saves some modified file-visiting buffers.  Normally
  801.      it asks the user about each buffer.  But if SAVE-SILENTLY-P is
  802.      non-`nil', it saves all the file-visiting buffers without querying
  803.      the user.
  804.  
  805.      The optional EXITING argument, if non-`nil', requests this
  806.      function to offer also to save certain other buffers that are not
  807.      visiting files.  These are buffers that have a non-`nil' local
  808.      value of `buffer-offer-save'.  (A user who says yes to saving one
  809.      of these is asked to specify a file name to use.)  The
  810.      `save-buffers-kill-emacs' function passes a non-`nil' value for
  811.      this argument.
  812.  
  813.  - Variable: buffer-offer-save
  814.      When this variable is non-`nil' in a buffer, XEmacs offers to save
  815.      the buffer on exit even if the buffer is not visiting a file.  The
  816.      variable is automatically local in all buffers.  Normally, Mail
  817.      mode (used for editing outgoing mail) sets this to `t'.
  818.  
  819.  - Command: write-file FILENAME
  820.      This function writes the current buffer into file FILENAME, makes
  821.      the buffer visit that file, and marks it not modified.  Then it
  822.      renames the buffer based on FILENAME, appending a string like `<2>'
  823.      if necessary to make a unique buffer name.  It does most of this
  824.      work by calling `set-visited-file-name' and `save-buffer'.
  825.  
  826.  - Variable: write-file-hooks
  827.      The value of this variable is a list of functions to be called
  828.      before writing out a buffer to its visited file.  If one of them
  829.      returns non-`nil', the file is considered already written and the
  830.      rest of the functions are not called, nor is the usual code for
  831.      writing the file executed.
  832.  
  833.      If a function in `write-file-hooks' returns non-`nil', it is
  834.      responsible for making a backup file (if that is appropriate).  To
  835.      do so, execute the following code:
  836.  
  837.           (or buffer-backed-up (backup-buffer))
  838.  
  839.      You might wish to save the file modes value returned by
  840.      `backup-buffer' and use that to set the mode bits of the file that
  841.      you write.  This is what `save-buffer' normally does.
  842.  
  843.      Even though this is not a normal hook, you can use `add-hook' and
  844.      `remove-hook' to manipulate the list.  *Note Hooks::.
  845.  
  846.  - Variable: local-write-file-hooks
  847.      This works just like `write-file-hooks', but it is intended to be
  848.      made local to particular buffers.  It's not a good idea to make
  849.      `write-file-hooks' local to a buffer--use this variable instead.
  850.  
  851.      The variable is marked as a permanent local, so that changing the
  852.      major mode does not alter a buffer-local value.  This is
  853.      convenient for packages that read "file" contents in special ways,
  854.      and set up hooks to save the data in a corresponding way.
  855.  
  856.  - Variable: write-contents-hooks
  857.      This works just like `write-file-hooks', but it is intended for
  858.      hooks that pertain to the contents of the file, as opposed to
  859.      hooks that pertain to where the file came from.  Such hooks are
  860.      usually set up by major modes, as buffer-local bindings for this
  861.      variable.  Switching to a new major mode always resets this
  862.      variable.
  863.  
  864.  - Variable: after-save-hook
  865.      This normal hook runs after a buffer has been saved in its visited
  866.      file.
  867.  
  868.  - Variable: file-precious-flag
  869.      If this variable is non-`nil', then `save-buffer' protects against
  870.      I/O errors while saving by writing the new file to a temporary
  871.      name instead of the name it is supposed to have, and then renaming
  872.      it to the intended name after it is clear there are no errors.
  873.      This procedure prevents problems such as a lack of disk space from
  874.      resulting in an invalid file.
  875.  
  876.      As a side effect, backups are necessarily made by copying.  *Note
  877.      Rename or Copy::.  Yet, at the same time, saving a precious file
  878.      always breaks all hard links between the file you save and other
  879.      file names.
  880.  
  881.      Some modes set this variable non-`nil' locally in particular
  882.      buffers.
  883.  
  884.  - User Option: require-final-newline
  885.      This variable determines whether files may be written out that do
  886.      *not* end with a newline.  If the value of the variable is `t',
  887.      then `save-buffer' silently adds a newline at the end of the file
  888.      whenever the buffer being saved does not already end in one.  If
  889.      the value of the variable is non-`nil', but not `t', then
  890.      `save-buffer' asks the user whether to add a newline each time the
  891.      case arises.
  892.  
  893.      If the value of the variable is `nil', then `save-buffer' doesn't
  894.      add newlines at all.  `nil' is the default value, but a few major
  895.      modes set it to `t' in particular buffers.
  896.  
  897. 
  898. File: lispref.info,  Node: Reading from Files,  Next: Writing to Files,  Prev: Saving Buffers,  Up: Files
  899.  
  900. Reading from Files
  901. ==================
  902.  
  903.    You can copy a file from the disk and insert it into a buffer using
  904. the `insert-file-contents' function.  Don't use the user-level command
  905. `insert-file' in a Lisp program, as that sets the mark.
  906.  
  907.  - Function: insert-file-contents FILENAME &optional VISIT BEG END
  908.           REPLACE
  909.      This function inserts the contents of file FILENAME into the
  910.      current buffer after point.  It returns a list of the absolute
  911.      file name and the length of the data inserted.  An error is
  912.      signaled if FILENAME is not the name of a file that can be read.
  913.  
  914.      The function `insert-file-contents' checks the file contents
  915.      against the defined file formats, and converts the file contents if
  916.      appropriate.  *Note Format Conversion::.  It also calls the
  917.      functions in the list `after-insert-file-functions'; see *Note
  918.      Saving Properties::.
  919.  
  920.      If VISIT is non-`nil', this function additionally marks the buffer
  921.      as unmodified and sets up various fields in the buffer so that it
  922.      is visiting the file FILENAME: these include the buffer's visited
  923.      file name and its last save file modtime.  This feature is used by
  924.      `find-file-noselect' and you probably should not use it yourself.
  925.  
  926.      If BEG and END are non-`nil', they should be integers specifying
  927.      the portion of the file to insert.  In this case, VISIT must be
  928.      `nil'.  For example,
  929.  
  930.           (insert-file-contents filename nil 0 500)
  931.  
  932.      inserts the first 500 characters of a file.
  933.  
  934.      If the argument REPLACE is non-`nil', it means to replace the
  935.      contents of the buffer (actually, just the accessible portion)
  936.      with the contents of the file.  This is better than simply
  937.      deleting the buffer contents and inserting the whole file, because
  938.      (1) it preserves some marker positions and (2) it puts less data
  939.      in the undo list.
  940.  
  941.    If you want to pass a file name to another process so that another
  942. program can read the file, use the function `file-local-copy'; see
  943. *Note Magic File Names::.
  944.  
  945. 
  946. File: lispref.info,  Node: Writing to Files,  Next: File Locks,  Prev: Reading from Files,  Up: Files
  947.  
  948. Writing to Files
  949. ================
  950.  
  951.    You can write the contents of a buffer, or part of a buffer, directly
  952. to a file on disk using the `append-to-file' and `write-region'
  953. functions.  Don't use these functions to write to files that are being
  954. visited; that could cause confusion in the mechanisms for visiting.
  955.  
  956.  - Command: append-to-file START END FILENAME
  957.      This function appends the contents of the region delimited by
  958.      START and END in the current buffer to the end of file FILENAME.
  959.      If that file does not exist, it is created.  If that file exists
  960.      it is overwritten.  This function returns `nil'.
  961.  
  962.      An error is signaled if FILENAME specifies a nonwritable file, or
  963.      a nonexistent file in a directory where files cannot be created.
  964.  
  965.  - Command: write-region START END FILENAME &optional APPEND VISIT
  966.      This function writes the region delimited by START and END in the
  967.      current buffer into the file specified by FILENAME.
  968.  
  969.      If START is a string, then `write-region' writes or appends that
  970.      string, rather than text from the buffer.
  971.  
  972.      If APPEND is non-`nil', then the specified text is appended to the
  973.      existing file contents (if any).
  974.  
  975.      If VISIT is `t', then XEmacs establishes an association between
  976.      the buffer and the file: the buffer is then visiting that file.
  977.      It also sets the last file modification time for the current
  978.      buffer to FILENAME's modtime, and marks the buffer as not
  979.      modified.  This feature is used by `save-buffer', but you probably
  980.      should not use it yourself.
  981.  
  982.      If VISIT is a string, it specifies the file name to visit.  This
  983.      way, you can write the data to one file (FILENAME) while recording
  984.      the buffer as visiting another file (VISIT).  The argument VISIT
  985.      is used in the echo area message and also for file locking; VISIT
  986.      is stored in `buffer-file-name'.  This feature is used to
  987.      implement `file-precious-flag'; don't use it yourself unless you
  988.      really know what you're doing.
  989.  
  990.      The function `write-region' converts the data which it writes to
  991.      the appropriate file formats specified by `buffer-file-format'.
  992.      *Note Format Conversion::.  It also calls the functions in the list
  993.      `write-region-annotate-functions'; see *Note Saving Properties::.
  994.  
  995.      Normally, `write-region' displays a message `Wrote file FILENAME'
  996.      in the echo area.  If VISIT is neither `t' nor `nil' nor a string,
  997.      then this message is inhibited.  This feature is useful for
  998.      programs that use files for internal purposes, files that the user
  999.      does not need to know about.
  1000.  
  1001. 
  1002. File: lispref.info,  Node: File Locks,  Next: Information about Files,  Prev: Writing to Files,  Up: Files
  1003.  
  1004. File Locks
  1005. ==========
  1006.  
  1007.    When two users edit the same file at the same time, they are likely
  1008. to interfere with each other.  XEmacs tries to prevent this situation
  1009. from arising by recording a "file lock" when a file is being modified.
  1010. XEmacs can then detect the first attempt to modify a buffer visiting a
  1011. file that is locked by another XEmacs process, and ask the user what to
  1012. do.
  1013.  
  1014.    File locks do not work properly when multiple machines can share
  1015. file systems, such as with NFS.  Perhaps a better file locking system
  1016. will be implemented in the future.  When file locks do not work, it is
  1017. possible for two users to make changes simultaneously, but XEmacs can
  1018. still warn the user who saves second.  Also, the detection of
  1019. modification of a buffer visiting a file changed on disk catches some
  1020. cases of simultaneous editing; see *Note Modification Time::.
  1021.  
  1022.  - Function: file-locked-p &optional FILENAME
  1023.      This function returns `nil' if the file FILENAME is not locked by
  1024.      this XEmacs process.  It returns `t' if it is locked by this
  1025.      XEmacs, and it returns the name of the user who has locked it if it
  1026.      is locked by someone else.
  1027.  
  1028.           (file-locked-p "foo")
  1029.                => nil
  1030.  
  1031.  - Function: lock-buffer &optional FILENAME
  1032.      This function locks the file FILENAME, if the current buffer is
  1033.      modified.  The argument FILENAME defaults to the current buffer's
  1034.      visited file.  Nothing is done if the current buffer is not
  1035.      visiting a file, or is not modified.
  1036.  
  1037.  - Function: unlock-buffer
  1038.      This function unlocks the file being visited in the current buffer,
  1039.      if the buffer is modified.  If the buffer is not modified, then
  1040.      the file should not be locked, so this function does nothing.  It
  1041.      also does nothing if the current buffer is not visiting a file.
  1042.  
  1043.  - Function: ask-user-about-lock FILE OTHER-USER
  1044.      This function is called when the user tries to modify FILE, but it
  1045.      is locked by another user named OTHER-USER.  The value it returns
  1046.      determines what happens next:
  1047.  
  1048.         * A value of `t' says to grab the lock on the file.  Then this
  1049.           user may edit the file and OTHER-USER loses the lock.
  1050.  
  1051.         * A value of `nil' says to ignore the lock and let this user
  1052.           edit the file anyway.
  1053.  
  1054.         * This function may instead signal a `file-locked' error, in
  1055.           which case the change that the user was about to make does
  1056.           not take place.
  1057.  
  1058.           The error message for this error looks like this:
  1059.  
  1060.                error--> File is locked: FILE OTHER-USER
  1061.  
  1062.           where `file' is the name of the file and OTHER-USER is the
  1063.           name of the user who has locked the file.
  1064.  
  1065.      The default definition of this function asks the user to choose
  1066.      what to do.  If you wish, you can replace the `ask-user-about-lock'
  1067.      function with your own version that decides in another way.  The
  1068.      code for its usual definition is in `userlock.el'.
  1069.  
  1070. 
  1071. File: lispref.info,  Node: Information about Files,  Next: Changing File Attributes,  Prev: File Locks,  Up: Files
  1072.  
  1073. Information about Files
  1074. =======================
  1075.  
  1076.    The functions described in this section all operate on strings that
  1077. designate file names.  All the functions have names that begin with the
  1078. word `file'.  These functions all return information about actual files
  1079. or directories, so their arguments must all exist as actual files or
  1080. directories unless otherwise noted.
  1081.  
  1082. * Menu:
  1083.  
  1084. * Testing Accessibility::   Is a given file readable?  Writable?
  1085. * Kinds of Files::          Is it a directory?  A symbolic link?
  1086. * Truenames::            Eliminating symbolic links from a file name.
  1087. * File Attributes::         How large is it?  Any other names?  Etc.
  1088.  
  1089.